<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<!-- Standard Head Part -->
<head>
<title>NUnit - Factory</title>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta http-equiv="Content-Language" content="en-US">
<link rel="stylesheet" type="text/css" href="nunit.css">
<link rel="shortcut icon" href="favicon.ico">
</head>
<!-- End Standard Head Part -->

<body>

<!-- Standard Header for NUnit.org -->
<div id="header">
  <a id="logo" href="http://www.nunit.org"><img src="img/logo.gif" alt="NUnit.org" title="NUnit.org"></a>
  <div id="nav">
    <a href="http://www.nunit.org">NUnit</a>
    <a class="active" href="index.html">Documentation</a>
  </div>
</div>
<!-- End of Header -->

<div id="content">

<script language="JavaScript" src="codeFuncs.js" ></script> <!-- Do it this way for IE -->

<h3>FactoryAttribute (NUnit 2.5)</h3>

<div style="text-align: center; margin: 2em 10%; padding: 4px 0; border: 2px solid black">
  <h4>Preliminary documentation, subject to change.</h4>
</div>

<p><b>FactoryAttribute</b> is used on a parameterized test method to
identify the test case factory (or factories) that will provide the required 
arguments. The attribute has four constructors.

<div class="code">
<pre>
Factory(Type factoryType, string factoryName);
Factory(Type factoryType);
Factory(string factoryName);
Factory();
</pre>
</div>

<p>If <b>factoryType</b> is specified, it represents the class that provides
the test case factory. If not, the class containing the test method is used.

<p>If <b>factoryName</b>, it represents the name of a field, property or
method that will provide the arguments. This field may contain a single
name or multiple names separated by commas. If no factoryName is given,
NUnit attempts to find factories that are compatible with the method
signature using information provided by the  <b>TestCaseFactoryAttribute</b>.

<p>Each test case factory has the following characteristics:
<ul>
<li>It may be a field, property or method.
<li>It may be either an instance or a static member.
<li>It must be an IEnumerable or a type that implemens IEnumerable.
<li>If you want NUnit to find the factory automatically (without specifying
it by name), it should be marked with a <b>TestCaseFactoryAttribute</b>.
</ul>

<p>NUnit locates the factories at the time the tests are loaded, creates
instances of each class with non-static factories and builds a list of 
tests to be executed. Each factory object is only created once at this
time and is destroyed after all tests are loaded. In the case of factories
located within the same class as the tests, a different object is created
each time the test is run, so no communication is possible using non-static
members of the class.

<p>In constructing tests, NUnit uses each item returned from the factory
enumerator as follows:
<ol>
<li><p>If it is an <b>object[]</b>, it is used directly to provide
the arguments for the method, as in this example, which returns
arguments from a named static field.

<div class="code">
<pre>[Test, Factory("DivideCases")]
public void DivideTest(int n, int d, int q)
{
    Assert.AreEqual( q, n / d );
}

static object[] DivideCases =
{
    new object[] { 12, 3, 4 },
    new object[] { 12, 2, 6 },
    new object[] { 12, 4, 3 } 
};
</pre></div>

<li><p>If it is an array of some other type, NUnit can use it provided
that the arguments to the method are all of that type. For example,
the above code could be modified to make the three nested arrays 
of type int[].

<li><p>If it is a single value type - like numerics or DateTime - it
is used directly as the sole argument to the method. The method must,
of course take a single argument of the same type for this to work.
This eliminates a bit of syntax on the part of the programmer, as in
this example:

<div class="code"><pre>
static int[] EvenNumbers = new int[] { 2, 4, 6, 8 };

[Test, Factory("EvenNumbers")]
public void TestMethod(int num)
{
    Assert.IsTrue( num % 2 == 0 );
}
</pre></div>

<p><b>Note:</b> Any user-defined struct intended to hold the arguments
will be passed directly to the test method, since a struct is a value type.
If you intend your user type to be used as described in the following item,
you must define it as a class.

<li><p>If it is any other type of object, it is examined using reflection
and any public fields or properties with the following names are used:
  <p><dl>
  <dt><b>Arguments</b>
  <dd>An <b>object[]</b> representing the arguments to the method
  <dt><b>Description</b>
  <dd>Sets the description property of the test
  <dt><b>ExpectedException</b>
  <dd>Specifies a the Type of an exception that should be thrown by this invocation
  <dt><b>ExpectedExceptionName</b>
  <dd>Specifies a the FullName of an exception that should be thrown by this invocation
  <dt><b>Result</b>
  <dd>The expected result to be returned from the method, which must have
      a compatible return type.
  <dt><b>TestName</b>
  <dd>Provides a name for the test. If not specified, a name is generated based on 
      the method name and the arguments provided
  </dl>
<p>
<p>Although any object with the required fields or properties may be used,
   NUnit provides the <b>TestCaseData</b> class for this purpose. The following 
   example returns <b>TestCaseData</b> instances from a data source in
   a separately defined class.

<div class="code">
<pre>[TestFixture]
public class MyTests
{
  [Test,Factory(typeof(MyFactoryClass)]
  public void DivideTest(int n, int d, int q)
  {
    Assert.AreEqual( q, n / d );
  }
	
  ...
}

public class MyFactoryClass
{
  [TestCaseFactory(typeof(int), typeof(int))]
  public static IEnumerable TestCases
  {
    get
    {
      yield return new TestCaseData( 12, 3 ).Returns( 4 );
      yield return new TestCaseData( 12, 2 ).Returns( 6 );
      yield return new TestCaseData( 12, 4 ).Returns( 3 );
      yield return new TestCaseData( 0, 0 )
        .Throws(typeof(DivideByZeroException))
        .With.TestName("DivideByZero")
        .With.Description("An exception is expected");
    }
  }  
}
</div>

<p>This example uses the fluent interface supported by <b>TestCaseData</b>
to make the program more readable. The last yield statement above  is equivalent to

<div class="code">
<pre>      TestCaseData data = new TestCaseData(0,0);
      data.ExpectedException = typeof(DivideByZeroException;
      data.TestName = "DivideByZero";
      data.Description = "An exception is expected";
      yield return data;
</pre>
</div> 

<p><b>TestCaseData</b> supports the following properties
and methods, which may be appended to an instance in any order.

<p>
<dl>
  <dt><b>.Returns</b>
  <dd>The expected result to be returned from the method, which must have
      a compatible return type.
  <dt><b>.Throws(Type)</b>
  <dt><b>.Throws(string)</b>
  <dd>Specifies a the Type or FullName of an exception that should be thrown by this invocation
  <dt><b>.With.Description(string)</b>
  <dd>Sets the description property of the test
  <dt><b>.With.TestName(string)</b>
  <dd>Provides a name for the test. If not specified, a name is generated based on 
      the method name and the arguments provided
</dl>
   

</div>

<!-- Submenu -->
<div id="subnav">
<ul>
<li><a href="index.html">NUnit 2.5</a></li>
<ul>
<li><a href="getStarted.html">Getting&nbsp;Started</a></li>
<li><a href="assertions.html">Assertions</a></li>
<li><a href="attributes.html">Attributes</a></li>
<ul>
<li><a href="testIdentification.html">Test&nbsp;Identification</a></li>
<li><a href="testSelection.html">Test&nbsp;Selection</a></li>
<li><a href="testModification.html">Test&nbsp;Modification</a></li>
<li><a href="setupTeardown.html">Setup&nbsp;and&nbsp;Teardown</a></li>
<li><a href="parameterizedTests.html">Parameterized&nbsp;Tests</a></li>
<ul>
<li><a href="combinatorial.html">Combinatorial</a></li>
<li id="current"><a href="factory.html">Factory</a></li>
<li><a href="pairwise.html">Pairwise</a></li>
<li><a href="random.html">Random</a></li>
<li><a href="range.html">Range</a></li>
<li><a href="sequential.html">Sequential</a></li>
<li><a href="testCase.html">Test&nbsp;Case</a></li>
<li><a href="testCaseFactory.html">Test&nbsp;Case&nbsp;Factory</a></li>
<li><a href="values.html">Values</a></li>
</ul>
</ul>
<li><a href="nunit-console.html">Console&nbsp;Runner</a></li>
<li><a href="nunit-gui.html">Gui&nbsp;Runner</a></li>
<li><a href="features.html">Other&nbsp;Features</a></li>
<li><a href="releaseNotes.html">Release&nbsp;Notes</a></li>
<li><a href="samples.html">Samples</a></li>
<li><a href="license.html">License</a></li>
</ul>
</ul>
</div>
<!-- End of Submenu -->


<!-- Standard Footer for NUnit.org -->
<div id="footer">
  Copyright &copy; 2008 Charlie Poole. All Rights Reserved.
</div>
<!-- End of Footer -->

</body>
</html>
